<?php
declare(ENCODING = 'utf-8');

/*
 * phpCR_RangeIteratorInterface.php created on 14 avr. 08 
 * Author: Rodrigue Le Gall
 * 
 * This file is inspired by the project phpCR of Travis Swicegood <development@domain51.com>
 *
 * RPortal is an open source web based Content Management System
 * Copyright (C) 2002-2008  Rodrigue Le Gall
 * 
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 */

/**
 * Extends Iterator with the {@link skip()}, {@link getSize()}
 * and {@link getPosition()} methods. 
 * 
 * This is the base interface of all type-specific iterators in 
 * {@link phpContentRepository} and its subpackages.
 *
 * {@link Item} is the base interface of {@link Node} and {@link Property}.
 *
 * @see NodeIterator, PropertyIterator
 *
 * @package phpContentRepository
 * @RPInterface
 */
interface phpCR_RangeIteratorInterface extends phpCR_IteratorInterface {

	/**
	 * Skip a number of elements in the iterator.
	 *
	 * @param integer $skipNum the non-negative number of elements to skip
	 * @throws phpCR_NoSuchElementException if skipped past the last element in the iterator.
	 */
	public function skip($skipNum);

	/**
	 * Returns the total number of of items available through this iterator.
	 * 
	 * For example, for some node $n, $n->getNodes()->getSize() returns the 
	 * number of child nodes of $n visible through the current Session. 
	 * 
	 * In some implementations precise information about the number of elements may 
	 * not be available. In such cases this method must return -1. API clients will 
	 * then be able to use RangeIterator->getNumberRemaining() to get an 
	 * estimate on the number of elements.
	 *
	 * @return integer
	 */
	public function getSize();

	/**
	 * Returns the current position within the iterator. The number
	 * returned is the 0-based index of the next element in the iterator,
	 * i.e. the one that will be returned on the subsequent next() call.
	 * 
	 * Note that this method does not check if there is a next element,
	 * i.e. an empty iterator will always return 0.
	 *
	 * @return integer
	 */
	public function getPosition();

	/**
	 * Returns the number of subsequent next() calls that can be
	 * successfully performed on this iterator. 
	 * 
	 * This is the  number of items still available through this iterator. For 
	 * example, for some node $n, $n->getNodes()->getSize() returns the number 
	 * of child nodes of $n visible through the current Session that have not 
	 * yet been returned. 
	 * 
	 * In some implementations precise information about the number of remaining
	 * elements may not be available. In such cases this method should return
	 * a reasonable upper bound on the number if such an estimate is available
	 * and -1 if it is not.
	 *
	 * @return integer
	 */
	public function getNumberRemaining();
}
